Node representing a jinja template.¶

Description

Renders templates with the context-aware MkNodes jinja environment. Rendered nodes become virtual children of this node. Additional variables can be passed to the render process.

ExamplesDocStringsSub classesBase classes⋔ Inheritance diagramNodeFileCode

Example: From project¶

Jinja

{{ "why_mknodes.jinja" | MkTemplate }}

Python

MkTemplate('why_mknodes.jinja', variables={})

RenderedMarkdownHtml

Welcome to the MkNodes universe!¶

Features

Move parts of the documentation generation process into the python space. You can easily switch between programmatically generating documentation and hand-writing documentation.
Easy access to more "advanced" theme customization options. The process of generating HTML page templates in MkDocs can be a bit cumbersome. Using MkNodes, you dont need to mess with HTML, and you dont have to manage a separate folder structure for the templates. Modifying MkPage.template will trigger an automated template generation process which also covers template inheritance, meaning you can also define templates for a complete tree section.
Write your site navigation using idiomatic python. As known from frameworks like flask, you can create the website tree hierarchy using a decorator-based routing approach. Moving the navigation part into the python space allows to easily create documentation parts programatically. Also, visual aspects like page icons / subtitles can be defined in the site navigation instead of in the page header metadata.
A large library of python classes representing different kinds of Markdown fragments (the MkNodes). These nodes range from basic elements like lists or tables up to nodes which will generate large documentation chunks for you automatically. A complete API documentation can get created with a handful lines of code.
A dead simple API. Working with MkNodes basically means: Create nodes, attach them to the tree and forget about them. For most nodes, you only need to learn about the __init__signature.
A fully-loaded jinja2 environment, with all information about your project available in the environment namespace. Also, all the MkNodes (approx 70 different nodes right now) are available as Jinja2 filters.
Separate content from layout. The nodes are context-aware, meaning that they show information of the project they are used in. You can write your own website template and use it for multiple projects.
Create complex, composable and re-usable "documentation widgets" yourself. It's easy to write your own MkNodes. If desired then these can be composed of other MkNodes, making them small sub-trees of your site tree. It is even possible to create nodes which represent a whole website.
Automatic resource management: The MkNodes know about the resources they require, like CSS, Javascript or markdown extensions. When the website gets assembled, this information can be used to automatically add all the required resources to the right place, like to the MkDocs config or to the HTML head by automatically creating HTML page templates.

# Welcome to the **MkNodes** universe!

Features

* Move parts of the documentation generation process into the python space. You can easily switch between programmatically generating documentation and hand-writing documentation.

* Easy access to more "advanced" theme customization options.
The process of generating HTML page templates in MkDocs can be a bit cumbersome. Using MkNodes, you dont need to mess with HTML, and you dont have to manage a separate folder structure for the templates. Modifying `MkPage.template` will trigger an automated template generation process which also covers template inheritance, meaning you can also define templates for a complete tree section.

* Write your site navigation using idiomatic python. As known from frameworks like flask, you can create the website tree hierarchy using a decorator-based routing approach. Moving the navigation part into the python space allows to easily create documentation parts programatically.
Also, visual aspects like page icons / subtitles can be defined in the site navigation instead of in the page header metadata.

* A large library of python classes representing different kinds of Markdown fragments (the **MkNodes**). These nodes range from basic elements like lists or tables up to nodes which will generate large documentation chunks for you automatically. A complete API documentation can get created with a handful lines of code.

* A dead simple API. Working with **MkNodes** basically means: Create nodes, attach them to the tree and forget about them. For most nodes, you only need to learn about the `__init__`signature.

* A fully-loaded **jinja2** environment, with all information about your project available in the environment namespace. Also, all the **MkNodes** (approx 70 different nodes right now) are available as **Jinja2** filters.

* Separate content from layout. The nodes are context-aware, meaning that they show information of the project they are used in. You can write your own website template and use it for multiple projects.

* Create complex, composable and re-usable "documentation widgets" yourself. It's easy to write your own **MkNodes**. If desired then these can be composed of other **MkNodes**, making them small sub-trees of your site tree. It is even possible to create nodes which represent a whole website.

* Automatic resource management: The MkNodes know about the resources they require, like CSS, Javascript or markdown extensions. When the website gets assembled, this information can be used to automatically add all the required resources to the right place, like to the MkDocs config or to the HTML head by automatically creating HTML page templates.

<h1 id="welcome-to-the-mknodes-universe">Welcome to the <strong>MkNodes</strong> universe!</h1>
<p>Features</p>
<ul>
<li>
<p>Move parts of the documentation generation process into the python space. You can easily switch between programmatically generating documentation and hand-writing documentation.</p>
</li>
<li>
<p>Easy access to more "advanced" theme customization options.
The process of generating HTML page templates in MkDocs can be a bit cumbersome. Using MkNodes, you dont need to mess with HTML, and you dont have to manage a separate folder structure for the templates. Modifying <code>MkPage.template</code> will trigger an automated template generation process which also covers template inheritance, meaning you can also define templates for a complete tree section.</p>
</li>
<li>
<p>Write your site navigation using idiomatic python. As known from frameworks like flask, you can create the website tree hierarchy using a decorator-based routing approach. Moving the navigation part into the python space allows to easily create documentation parts programatically.
Also, visual aspects like page icons / subtitles can be defined in the site navigation instead of in the page header metadata.</p>
</li>
<li>
<p>A large library of python classes representing different kinds of Markdown fragments (the <strong>MkNodes</strong>). These nodes range from basic elements like lists or tables up to nodes which will generate large documentation chunks for you automatically. A complete API documentation can get created with a handful lines of code.</p>
</li>
<li>
<p>A dead simple API. Working with <strong>MkNodes</strong> basically means: Create nodes, attach them to the tree and forget about them. For most nodes, you only need to learn about the <code>__init__</code>signature.</p>
</li>
<li>
<p>A fully-loaded <strong>jinja2</strong> environment, with all information about your project available in the environment namespace. Also, all the <strong>MkNodes</strong> (approx 70 different nodes right now) are available as <strong>Jinja2</strong> filters.</p>
</li>
<li>
<p>Separate content from layout. The nodes are context-aware, meaning that they show information of the project they are used in. You can write your own website template and use it for multiple projects.</p>
</li>
<li>
<p>Create complex, composable and re-usable "documentation widgets" yourself. It's easy to write your own <strong>MkNodes</strong>. If desired then these can be composed of other <strong>MkNodes</strong>, making them small sub-trees of your site tree. It is even possible to create nodes which represent a whole website.</p>
</li>
<li>
<p>Automatic resource management: The MkNodes know about the resources they require, like CSS, Javascript or markdown extensions. When the website gets assembled, this information can be used to automatically add all the required resources to the right place, like to the MkDocs config or to the HTML head by automatically creating HTML page templates.</p>
</li>
</ul>

Bases: MkContainer

init ¶

__init__(
    template: str,
    *,
    block: str | None = None,
    variables: dict[str, Any] | None = None,
    **kwargs: Any
)

Parameters:

Name	Type	Description	Default
`template`	`str`	Jinja template name.	required
`block`	`str \| None`	Name of a specific block of the template which should get rendered	`None`
`variables`	`dict[str, Any] \| None`	Variables to use for rendering	`None`
`kwargs`	`Any`	Keyword arguments passed to parent	`{}`

Name	Children	Inherits
MkCliDoc mknodes.basenodes.mkclidoc Node for showing documentation for click / typer CLI apps.		MkTemplate
MkMaterialBadge mknodes.basenodes.mkmaterialbadge Node for a CSS-based badge a la MkDocs-Material.		MkTemplate
MkImageCompare mknodes.basenodes.mkimagecompare Node to show an Image comparison (using a slider).		MkTemplate
MkImageSlideshow mknodes.basenodes.mkimageslideshow Node to show an Image slideshow (in autoplay mode).		MkTemplate
MkIFrame mknodes.basenodes.mkiframe Node for embedding an IFrame.		MkTemplate
MkCard mknodes.basenodes.mkcard A card node, displaying an image, a button-like label and a hover caption.		MkTemplate
MkInstallGuide mknodes.templatenodes.mkinstallguide Node to display an install guide.		MkTemplate
MkCodeOfConduct mknodes.templatenodes.mkcodeofconduct Node for a code of conduct section.		MkTemplate
MkCommitConventions mknodes.templatenodes.mkcommitconventions Text node containing Commit message conventions.		MkTemplate
MkPullRequestGuidelines mknodes.templatenodes.mkpullrequestguidelines Node showing pull request guidelines.		MkTemplate
MkDevEnvSetup mknodes.templatenodes.mkdevenvsetup Text node containing Instructions to set up a dev environment.		MkTemplate
MkDevTools mknodes.templatenodes.mkdevtools Node showing information about used dev tools.		MkTemplate
MkReprRawRendered mknodes.templatenodes.mkreprrawrendered Node showing a tabbed block to visualize a node in different representations.		MkTemplate
MkCommandOutput mknodes.templatenodes.mkcommandoutput Node to display the terminal output of a command.		MkTemplate
MkCommentedCode mknodes.templatenodes.mkcommentedcode Node which displays a list of code / comment blocks for given code.		MkTemplate
MkConfigSetting mknodes.templatenodes.mkconfigsetting Node for describing a config setting.		MkTemplate
MkPluginFlow mknodes.templatenodes.mkpluginflow Node showing info about the different stages of an MkDocs plugin.		MkTemplate

Name	Children	Inherits
MkContainer mknodes.basenodes.mkcontainer A node containing other MkNodes.	MkBlock MkAdmonition MkBlockQuote MkCode MkTemplate MkList MkBaseTable MkTab MkTabContainer MkCritic MkAnnotation ...	MkNode

graph TD
  94721308869584["mktemplate.MkTemplate"]
  94721311697232["mkcontainer.MkContainer"]
  94721308848336["mknode.MkNode"]
  94721311766592["node.Node"]
  140564252373184["builtins.object"]
  94721311697232 --> 94721308869584
  94721308848336 --> 94721311697232
  94721311766592 --> 94721308848336
  140564252373184 --> 94721311766592

/home/runner/work/mknodes/mknodes/mknodes/templatenodes/mktemplate/metadata.toml

[metadata]
icon = "simple-icons:jinja"
name = "MkTemplate"
virtual_children = true

[examples.regular]
title = "From project"
jinja = """
{{ "why_mknodes.jinja" | MkTemplate }}
"""

mknodes.templatenodes.mktemplate.MkTemplate
class MkTemplate(mkcontainer.MkContainer):
    """Node representing a jinja template.

    Renders templates with the context-aware MkNodes jinja environment.
    Rendered nodes become virtual children of this node.
    Additional variables can be passed to the render process.
    """

    ICON = "simple/jinja"
    STATUS = "new"
    VIRTUAL_CHILDREN = True

    def __init__(
        self,
        template: str,
        *,
        block: str | None = None,
        variables: dict[str, Any] | None = None,
        **kwargs: Any,
    ):
        """Constructor.

        Args:
            template: Jinja template name.
            block: Name of a specific block of the template which should get rendered
            variables: Variables to use for rendering
            kwargs: Keyword arguments passed to parent
        """
        super().__init__(**kwargs)
        self.template = template
        self.block = block
        self.variables = variables or {}

    @property
    def items(self):
        self.env.render_template(
            self.template,
            variables=self.variables,
            block_name=self.block,
        )
        return self.env.rendered_children

    @items.setter
    def items(self, val):
        pass

    def _to_markdown(self) -> str:
        return self.env.render_template(
            self.template,
            variables=self.variables,
            block_name=self.block,
        )

Node representing a jinja template.¶

Example: From project¶

Welcome to the MkNodes universe!¶

__init__ ¶

init ¶